14장 깃허브와 함께 일하기 (입문판)

출처: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 6가지만 가져가세요. 1. 깃허브 이슈가 무엇이고, 왜 작업을 이슈로 적어두면 편한지 설명한다. 2. gh CLI(깃허브 명령줄 도구)를 설치하고 내 계정과 연결하는 과정을 따라 한다. 3. 레이블(꼬리표)을 한 번에 만들어 이슈를 색깔로 구분한다. 4. 큰 작업을 작은 이슈 여러 개로 쪼개는 /decompose-issue 명령을 따라 한다. 5. 이슈 하나를 처음부터 끝까지 해결하는 /resolve-issue 명령을 따라 한다. 6. 여러 이슈를 동시에 처리하는 병렬 작업 방식을 구분한다.

이 장에서 나오는 명령이나 설치 절차, 버전 번호는 원서/노트 기준 예시이며, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하세요.

---

들어가기 전에

이런 적 있죠? 혼자 코딩할 때는 "이거 고쳐야지" 하고 머릿속에만 담아둡니다. 그런데 막상 다음 날이 되면 뭘 고치려 했는지 까먹습니다. 친구랑 같이 만드는 프로젝트라면 더 심합니다. "그거 누가 하기로 했더라?" "그 버그 고쳤어 아직이야?" 하고 매번 물어봐야 합니다.

이렇게 머릿속이나 카톡으로 떠다니던 "할 일"을 한 곳에 적어두고 누구나 볼 수 있게 만든 게 바로 깃허브 이슈입니다. 이 장은 그 이슈를 클로드 코드와 함께 만들고, 분류하고, 해결하는 방법을 다룹니다.

이 장은 앞에서 배운 몇 가지를 가볍게 씁니다. 커스텀 슬래시 커맨드(직접 만드는 /명령, 5장), 서브에이전트(일을 나눠 맡는 보조 AI, 7장), Git Worktree(작업 공간 여러 개, 13장)입니다. 지금 기억이 안 나도 괜찮습니다. 필요한 부분은 이 장 안에서 한 줄씩 다시 짚어줍니다.

새 용어 미리 한 줄씩: 이슈(issue): 프로젝트에서 "이거 해야 한다"를 적어둔 쪽지 한 장. 포스트잇 한 장이라고 보면 됩니다. CLI: "명령줄 도구"의 줄임말. 마우스 클릭 대신 글자를 쳐서 컴퓨터에 시키는 방식. 라면 끓일 때 버튼 대신 손으로 직접 불 조절하는 느낌입니다. 풀 리퀘스트(PR): "내가 고친 코드를 합쳐주세요" 하고 내미는 신청서. 숙제 검사 맡기듯 코드를 제출하는 것입니다.

---

14-1 깃허브 이슈 이해하기

이렇게 막힌 적 있죠?

식당을 연다고 생각해 봅시다. "새 메뉴 추가하자" "에어컨 고쳐야 해" "디저트 코너 만들면 어때?" 이런 말들이 하루에도 수십 개 나옵니다. 그런데 적어두지 않으면 다 잊어버립니다.

이걸 "업무 요청서" 한 장씩으로 만들어 한 통에 모아두면 어떨까요? - "새 메뉴 추가하자" → 새 기능 요청서 - "에어컨 고쳤어야 해" → 고장 신고서 - "디저트 코너 만들면 어때?" → 아이디어 제안서

이렇게 할 일을 한 장씩 적어 한 곳에 모은 것, 그게 바로 깃허브 이슈입니다.

그게 바로 이슈

이슈는 프로젝트의 개선점, 버그, 아이디어를 한 장씩 적어 관리하는 깃허브의 "작업 쪽지"입니다. 모든 논의와 할 일을 한 곳에 모아두는 게 핵심입니다.

비유	클로드 코드에서	주의
식당 업무 요청서 한 장	깃허브 이슈 한 개	한 이슈에 여러 일을 욱여넣지 말 것. 한 장에 한 가지 일만
요청서를 모아둔 통	깃허브의 이슈 목록	적어두지 않으면 클로드 코드도 협업자도 그 일을 모름
빨강/파랑 색 태그	레이블 (14-3에서)	이슈가 많아지면 분류가 필수

이슈를 이루는 7가지 요소

이슈 한 장에는 보통 다음 7가지가 들어갑니다. 처음엔 제목과 본문만 채워도 충분합니다. 나머지는 익숙해지면 하나씩 붙이면 됩니다.

요소	영문	무슨 역할인가	쉬운 예
제목과 본문	Title & Body	무슨 일인지 알려줌	제목 "로그인 버튼이 안 눌려요", 본문에 자세한 상황
담당자	Assignee	누가 할지 정함	"이건 내가 할게" 하고 이름 붙이기
레이블	Labels	종류/우선순위를 색으로 구분	bug(버그), feature(기능) 꼬리표
마일스톤	Milestone	목표/버전끼리 묶음	"v1.0 출시" 묶음에 75% 진행 표시
프로젝트	Project	칸반 보드로 한눈에 봄	할 일 / 하는 중 / 끝 칸으로 드래그
연결된 풀 리퀘스트	Linked PR	고친 코드를 이슈에 붙임	PR이 합쳐지면 이슈 자동으로 닫힘

용어 한 줄: 마일스톤(milestone)이란 "여기까지 끝내자"는 중간 목표 지점입니다. 마라톤의 5km, 10km 표지판 같은 것입니다. 용어 한 줄: 칸반 보드란 할 일을 "할 일 / 하는 중 / 끝" 칸에 카드로 붙여 옮기는 화이트보드입니다.

이슈 없이 일하면 왜 곤란할까

잘못된 예 (이슈 없이): 클로드 코드가 너무 빠르게 코드를 막 고칩니다. 무엇을 왜 고쳤는지 글로 남지 않습니다. 협업자는 "이게 뭐가 바뀐 거야?" 하고 어리둥절합니다.

올바른 예 (이슈로): 먼저 "로그인 버튼 고치기" 이슈를 만듭니다. 레이블과 담당자를 붙입니다. 일이 끝나면 PR을 이슈에 연결합니다. 누구나 무슨 일이 어떻게 끝났는지 한눈에 봅니다.

이럴 때 이렇게: 버그를 신고할 때는 본문에 세 가지를 꼭 적습니다. (1) 어떻게 하면 버그가 다시 나오는지(재현 방법), (2) 원래 어떻게 동작해야 하는지(예상 결과), (3) 실제로 어떻게 동작했는지(실제 결과)입니다. 이 셋만 있어도 고치는 사람이 헤매지 않습니다.

짧게 정리

이슈는 프로젝트의 할 일과 논의를 한 곳에 모으는 도구입니다. 7가지 요소(제목, 본문, 담당자, 레이블, 마일스톤, 프로젝트, 연결된 PR)가 있습니다. 처음엔 제목과 본문만으로 시작해도 됩니다.

---

14-2 깃허브 CLI 설치하기

이렇게 막힌 적 있죠?

이슈 하나 만들려고 깃허브 웹사이트에 들어갑니다. 로그인하고, 저장소 찾아 들어가고, 버튼 누르고, 또 폼 채우고... 하루에 이슈를 열 개 만든다면 이 클릭질이 너무 번거롭습니다.

이럴 때 터미널에서 글자 한 줄로 바로 이슈를 만들 수 있다면 어떨까요? 그걸 가능하게 해주는 도구가 gh CLI입니다.

그게 바로 gh CLI

gh CLI는 깃허브를 터미널에서 직접 다루는 "깃허브 공식 리모컨"입니다. TV 앞까지 안 가도 리모컨으로 채널 돌리듯, 웹사이트에 안 들어가도 터미널에서 바로 이슈를 만들고 PR을 올립니다.

비유	클로드 코드에서	주의
TV 리모컨	gh CLI 명령 (gh issue, gh pr ...)	리모컨이 없으면(설치 안 하면) 클로드 코드도 깃허브를 못 다룸
리모컨에 건전지 넣기	gh auth login 으로 계정 연결	연결 안 하면 "넌 누구냐"며 깃허브가 막음
안방 TV용 리모컨	내 계정/내 저장소에 연결됨	다른 사람 저장소를 마음대로 못 건드림

연동 방식은 두 가지, 추천은 하나

깃허브를 클로드 코드와 잇는 방법은 두 가지가 있습니다.

방식	한 줄 설명	추천?
MCP	MCP 서버를 통해 잇는 방식	노트 기준으로는 비추천
gh CLI	깃허브 공식 명령줄 도구	추천

용어 한 줄: MCP(Model Context Protocol)란 AI에게 외부 도구를 연결해주는 표준 규격입니다. 콘센트 규격(220V 플러그)처럼 "이렇게 꽂으면 통한다"는 약속입니다.

노트 기준으로 깃허브 연동은 MCP보다 gh CLI가 공식 추천 방식입니다. 어느 쪽이 추천인지는 시간이 지나면 바뀔 수 있으니, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하세요.

gh CLI 설치하기 (안전한 길)

자기 컴퓨터 종류에 맞는 한 줄만 치면 됩니다. 설치 명령은 운영체제마다 다릅니다.

터미널 예:

# 윈도우 (WinGet)
winget install --id GitHub.cli

# 윈도우 (Chocolatey)
choco install gh

# macOS (Homebrew)
brew install gh

설치가 잘 됐는지 확인:

gh --version
# 예: gh version 2.74.2 (2025-06-17)

위 버전 숫자는 노트 기준 예시입니다. 실제로는 더 높은 번호가 나올 수 있고, 그래도 정상입니다. 최신 값은 공식 문서에서 확인하세요.

계정 연결하기 (gh auth login 9단계 따라 하기)

설치만으로는 부족합니다. "이 리모컨은 내 거다"라고 알려주는 인증이 필요합니다. gh auth login 한 줄을 치면 질문이 하나씩 나오는데, 다음 순서대로 답하면 됩니다.

01. gh auth login 실행
02. gh --version 으로 설치 확인 (이미 했으면 통과)
03. Where do you use GitHub?           → GitHub.com 선택
04. What is your preferred protocol?   → SSH 선택
05. Upload your SSH public key         → 기존 공개키 선택
06. Title for your SSH key             → 그냥 Enter (기본값)
07. How would you like to authenticate? → Login with a web browser
08. Press Enter to open...             → Enter
09. 브라우저에서 내 깃허브 계정 선택    → 연동 완료

용어 한 줄: SSH란 컴퓨터끼리 안전하게 주고받는 자물쇠-열쇠 방식입니다. 비밀번호를 매번 치지 않고, 미리 만들어둔 열쇠로 문을 여는 것과 비슷합니다. 용어 한 줄: 공개키(public key)란 SSH 열쇠 한 쌍 중 "남에게 보여줘도 되는 쪽"입니다. 자물쇠는 남 줘도 되지만, 그 자물쇠를 여는 열쇠(개인키)는 나만 갖습니다.

4단계에서 SSH를 고르면 더 안전한 인증이 됩니다. 7단계의 웹 브라우저 인증은 비밀번호를 터미널에 직접 안 쳐도 돼서 편합니다.

연결 후 바로 써보기

연결이 끝나면 클로드 코드가 깃허브를 자동으로 다룰 수 있습니다. 손으로 직접 써볼 수 있는 기본 명령도 익혀두면 좋습니다.

터미널 예:

# 이슈 목록 보기
gh issue list

# 이슈 만들기
gh issue create --title "버그 수정" --body "상세 내용"

# PR 만들기
gh pr create --title "기능 추가" --body "설명"

# 이슈 한 개 자세히 보기 (200번 이슈)
gh issue view 200 --json title,body,labels,state

잘못된 예 vs 올바른 예: 잘못된 예 — gh CLI를 설치만 하고 gh auth login을 건너뛰면, 명령을 쳐도 "로그인하라"는 오류가 납니다. 올바른 예 — 설치 → gh auth login으로 계정 연결 → 그다음 gh issue create 사용.

이럴 때 이렇게: 처음 연결이 잘 됐는지 자신 없다면 gh issue list를 한번 쳐보세요. 이슈 목록이 나오면 연결 성공입니다. 오류가 나면 gh auth login을 다시 해보면 됩니다.

짧게 정리

gh CLI는 깃허브를 터미널에서 다루는 공식 도구입니다. 설치(winget/choco/brew) 다음 gh auth login으로 계정을 연결합니다. 연결 방식은 SSH + 웹 브라우저 인증을 권장합니다. 연결되면 클로드 코드가 깃허브를 자동으로 활용합니다.

---

14-3 레이블 생성하기

이렇게 막힌 적 있죠?

이슈가 5개일 때는 제목만 봐도 다 압니다. 그런데 이슈가 50개로 늘어나면? "급한 버그가 어디 있더라" "프론트엔드 일만 골라 보고 싶은데" 하고 한참 헤맵니다.

이럴 때 이슈마다 색깔 꼬리표를 붙여두면 한눈에 구분됩니다. 그 꼬리표가 바로 레이블입니다.

그게 바로 레이블

레이블은 이슈에 붙이는 "색깔 태그"입니다. 파일철에 빨강(긴급), 파랑(일반), 노랑(참고) 태그를 붙여 구분하듯, 이슈에도 종류와 난이도를 색으로 표시합니다.

비유	클로드 코드에서	주의
서류철 색깔 태그	깃허브 레이블	색만 다르고 이름 규칙이 없으면 오히려 헷갈림
빨강=긴급, 파랑=일반	종류:버그, 영역:프론트엔드 같은 이름	팀끼리 이름 규칙을 미리 합의해야 함
태그로 빨강만 골라 보기	레이블로 이슈 필터링	레이블이 없으면 필터도 못 함

레이블은 4가지 묶음으로 정리

레이블을 아무렇게나 만들면 또 헷갈립니다. 그래서 보통 네 가지 묶음으로 나눕니다.

묶음	예시	언제 쓰나
개발 영역	프론트엔드, 백엔드, DevOps	이 일이 어느 영역인지 표시
복잡도	복잡, 보통, 쉬움	얼마나 어려운지 표시 (모델 선택 기준도 됨)
작업 유형	다큐멘테이션, 기능, 테스트, 버그, 리팩터링	이 일이 무슨 성격인지 표시
도메인	사용자, 상품, 결제	어느 사업 영역인지 표시 (선택)

용어 한 줄: DevOps란 개발(Dev)과 운영(Ops)을 합친 말로, 코드를 실제 서버에 올리고 굴러가게 하는 배포/인프라 일을 뜻합니다. 용어 한 줄: 리팩터링이란 동작은 그대로 두고 코드를 더 깔끔하게 정리하는 일입니다. 방을 새로 짓진 않고 어질러진 물건만 제자리에 두는 것과 같습니다.

레이블 한꺼번에 만들기

레이블은 gh label create 명령으로 만듭니다. 하지만 손으로 다 칠 필요는 없습니다. 클로드 코드에게 "이런 레이블들을 만들어줘"라고 부탁하면, 아래 명령들을 알아서 만들어줍니다.

터미널 예 (개발 영역 일부):

gh label create "영역:프론트엔드" --description "프론트엔드 관련 작업" --color "D4F4FA"
gh label create "영역:백엔드" --description "백엔드 관련 작업" --color "E9DEFA"
gh label create "영역:DevOps" --description "배포 및 인프라 작업" --color "FBE6C6"

터미널 예 (복잡도):

gh label create "복잡도:복잡" --description "상당한 노력이 필요한 복잡한 작업" --color "F9D0C4"
gh label create "복잡도:보통" --description "일반적인 수준의 작업" --color "FEF2C0"
gh label create "복잡도:쉬움" --description "간단하고 빠르게 처리할 수 있는 작업" --color "B4E1D2"

터미널 예 (작업 유형):

gh label create "종류:다큐멘테이션" --description "문서 작성 또는 수정" --color "C5DEF5"
gh label create "종류:기능" --description "새로운 기능 개발" --color "F4B6C2"
gh label create "종류:테스트" --description "테스트 코드 작성 또는 리팩터링" --color "D4C5F9"
gh label create "종류:버그" --description "버그 수정" --color "f29513"
gh label create "종류:리팩터링" --description "코드 품질 개선" --color "a2eeef"

--color 뒤의 6자리는 색을 가리키는 코드입니다. 색 코드는 외워서 손으로 치는 게 아니라, 클로드 코드가 알아서 채워주니 가볍게 봐도 됩니다.

복잡도 레이블의 똑똑한 쓰임

복잡도 레이블은 단순 표시 이상의 쓸모가 있습니다. 이슈가 얼마나 어려운지에 따라 어떤 클로드 모델을 쓸지 고르는 기준이 됩니다.

일상 비유: 어려운 수학 문제는 똑똑한 전문가에게, 쉬운 덧셈은 빠른 일반 직원에게 맡기는 것과 같습니다.

노트 기준 매칭: - 복잡도:복잡 → 성능이 높은 클로드 Opus - 복잡도:쉬움 → 빠르고 비용 효율적인 클로드 Sonnet

어떤 모델 이름과 어떤 난이도가 맞는지는 시간이 지나면 바뀔 수 있으니, 최신 값은 공식 문서(클로드 코드 공식 문서)에서 확인하세요.

레이블의 또 다른 쓸모: (1) 여러 작업을 나눠 맡길 때 서로 안 겹치는지 확인하기 쉬움, (2) 원하는 이슈만 빠르게 골라 보기(필터링).

짧게 정리

레이블은 이슈를 색깔로 구분하는 꼬리표입니다. 영역, 복잡도, 유형, 도메인 4가지 묶음으로 정리합니다. 클로드 코드에게 부탁하면 gh label create 명령을 알아서 만들어줍니다. 복잡도 레이블은 어떤 모델을 쓸지 고르는 기준으로도 씁니다.

---

14-4 이슈 생성하기

이렇게 막힌 적 있죠?

"사용자 프로필 페이지 만들어 줘"라고 한 번에 부탁하면 어떻게 될까요? 일이 너무 커서 어디부터 손대야 할지 막막합니다. 중간에 하나가 틀어지면 전부 다시 해야 할 수도 있습니다.

이럴 때 큰 일을 작은 일 여러 개로 미리 쪼개두면 훨씬 수월합니다. 이 쪼개기를 자동으로 해주는 게 /decompose-issue 명령입니다.

그게 바로 /decompose-issue

큰 피자 한 판을 한입에 먹을 순 없습니다. 조각으로 나누면 하나씩 먹을 수 있습니다.

/decompose-issue는 "사용자 프로필 페이지 만들기"라는 피자 한 판을 - 프로필 이미지 변경 (1조각) - 비밀번호 변경 (1조각) - 소개 변경 (1조각) - 로그아웃 (1조각) 처럼 조각으로 나누는 명령입니다. 각 조각이 깃허브 이슈 하나가 됩니다.

비유	클로드 코드에서	주의
피자를 조각으로 나누기	큰 작업을 작은 이슈로 분해	너무 잘게 쪼개도 관리가 번거로움. 적당한 크기로
조각 하나씩 먹기	이슈 하나씩 해결	작을수록 한 번에 끝내기 쉬움
직접 만든 /명령	커스텀 슬래시 커맨드	5장에서 배운 방식 그대로

용어 한 줄: 커스텀 슬래시 커맨드란 내가 직접 만들어 두고 /이름으로 부르는 단축 명령입니다. 자주 쓰는 긴 부탁을 버튼 하나로 만든 셈입니다(5장). 용어 한 줄: 아규먼트(argument)란 명령에 같이 넘기는 "재료"입니다. /decompose-issue 뒤에 적는 작업 설명이 아규먼트입니다.

/decompose-issue 명령은 어떻게 생겼나

이 명령은 파일 하나로 만듭니다.

파일 위치: .claude/commands/decompose-issue.md

파일 안에는 클로드 코드에게 "이렇게 일하라"고 적습니다. 핵심만 보면:

# 작업 세분화하기
너는 이제부터 작업을 세분화하는 전략 전문가야.
아규먼트로 받은 작업을 독립적인 여러 개의 이슈로 분해해 줘.

## 작업 순서
1. 작업 분석: 핵심 요구사항과 목표 이해하기
2. 작업 분해: 더 작고 다루기 쉬운 하위 작업으로 나누기
3. 의존성 분석: 먼저 끝나야 하는 일이 있는지 파악하기
4. 분해된 이슈 출력: 나눈 결과 보여주기
5. 깃허브에 생성할지 묻기: 사용자가 결정하게 하기

이 명령은 5단계로 움직입니다: 분석 → 분해 → 의존성 → 출력 → 생성.

용어 한 줄: 의존성이란 "이게 먼저 끝나야 저걸 할 수 있다"는 순서 관계입니다. 라면 끓이려면 물부터 끓여야 하는 것과 같습니다.

마지막 5단계가 중요합니다. 클로드 코드가 멋대로 이슈를 올리지 않고, "이대로 만들까요?" 하고 먼저 물어봅니다. 사용자가 "응 만들어줘"라고 답해야 그때 깃허브에 올립니다.

이슈 템플릿 — 빈칸 채우기 양식

이슈를 매번 자유롭게 쓰면 사람마다 형식이 달라 헷갈립니다. 그래서 빈칸 채우기 양식(이슈 템플릿)을 정해둡니다.

용어 한 줄: 이슈 템플릿이란 이슈를 만들 때 따르는 정해진 양식입니다. 택배 송장처럼 칸이 정해져 있어 누가 써도 같은 형식이 됩니다.

양식의 뼈대:

title: [종류] 명확하고 실행 가능한 제목
labels:
- 종류:기능 | 종류:버그 | 종류:리팩터링 | 종류:테스트 | 종류:다큐멘테이션
- 영역:프론트엔드 | 영역:백엔드 | 영역:DevOps
- 복잡도:쉬움 | 복잡도:보통 | 복잡도:복잡
---
## 설명
[무엇을, 왜 해야 하는지]
## 작업 유형
- [ ] 백엔드 / 프론트엔드 / 풀스택 / 기타
## 완료 조건
- [ ] 요구사항 1, 2 ...
- [ ] 테스트 통과 / 린팅 통과 / 문서 업데이트
## 구현 참고사항
### 수정할 파일 / 따를 패턴 / 기술적 고려사항
## 의존성
- [ ] 이슈 #[번호]가 먼저 완료되어야 함

용어 한 줄: 완료 조건이란 "여기까지 되면 이 이슈는 끝"이라고 미리 정한 체크리스트입니다. 숙제 검사 기준표 같은 것입니다. 용어 한 줄: 린팅(linting)이란 코드에 오타나 규칙 위반이 없는지 자동으로 검사하는 일입니다. 맞춤법 검사기의 코드 버전입니다.

실제로 쪼개보기

프롬프트 예:

/decompose-issue 사용자 프로필 페이지를 완성하려고 해.
프로필 이미지 변경, 비밀번호 변경, 소개 변경, 로그아웃을 할 수 있게 구성해 줘.

클로드 코드의 분해 결과:

→ 이슈 #1: 프로필 이미지 변경
→ 이슈 #2: 비밀번호 변경 기능 구현
→ 이슈 #3: 소개 변경
→ 이슈 #4: 로그아웃

우선순위 추천:
→ #1과 #3은 서로 독립적이라 병렬로 진행 가능
→ #1이 끝난 뒤 #2와 #4 진행

이렇게 큰 일이 작은 이슈 4개로 깔끔하게 나뉩니다.

쪼갠 이슈 한 장은 이렇게 자세하다 (이슈 #2 예)

위에서 나온 이슈 #2(비밀번호 변경)를 양식대로 채우면 이렇게 됩니다. 한 장에 무엇을 어디서 어떻게 할지가 다 적혀 있습니다.

title: [기능] 비밀번호 변경 기능 구현
labels: 종류:기능, 영역:풀스택, 복잡도:복잡

## 설명
사용자가 현재 비밀번호를 확인하고 새 비밀번호로 바꿀 수 있는 기능을 만든다.

## 완료 조건
- 비밀번호 변경 폼 만들기
- 현재 비밀번호 검증
- 새 비밀번호 강도 검증
- 서버 동작 구현
- 비밀번호 업데이트 API 연동
- 성공/실패 안내 표시
- 테스트 통과 / 린팅 통과

## 구현 참고사항
### 수정할 파일
- components/profile/password-change-form.tsx — 새 컴포넌트
- app/actions/auth/change-password.ts — 새 서버 동작
- lib/validations/auth.ts — 검증 규칙 추가
- app/profile/edit/page.tsx — 변경 섹션 추가

### 기술적 고려사항
- 비밀번호 강도 검증 (최소 8자, 대소문자, 숫자, 특수문자)
- 너무 자주 시도하지 못하게 제한(rate limiting) 고려

## 의존성
- 이슈 #1이 먼저 완료되어야 함

## 예상 소요 시간
4-8시간

용어 한 줄: rate limiting이란 "짧은 시간에 너무 많이 시도하면 막기"입니다. ATM에서 비밀번호를 여러 번 틀리면 잠기는 것과 같습니다.

잘못된 예 vs 올바른 예: 잘못된 예 — "비밀번호 변경 만들어"처럼 한 줄만 적으면, 무엇이 끝난 건지 기준이 없어 어디서 멈춰야 할지 모릅니다. 올바른 예 — 위처럼 완료 조건을 체크리스트로 적으면, 그 칸이 다 채워질 때 "끝"이라고 명확히 판단할 수 있습니다.

"따를 패턴" 한 줄로 결과를 프로젝트와 맞추기

새 식당에 알바생이 처음 출근했다고 해봅시다. 아무 말 없이 "음료 좀 만들어줘"라고만 하면, 그 사람은 자기 집에서 타던 방식으로 만듭니다. 그런데 "우리 가게는 시럽을 먼저 붓고 얼음을 나중에 넣어요"라고 한마디 일러주면, 첫 잔부터 우리 가게 맛이 납니다.

클로드 코드도 똑같습니다. 이슈 본문에 그냥 "비밀번호 변경 만들어"라고만 적으면, 우리 프로젝트가 이미 쓰는 방식과 다른 방식으로 짤 수 있습니다. 그래서 이슈 템플릿의 구현 참고사항 안에 "따를 패턴" 칸을 두고, 우리 프로젝트가 이미 쓰는 방식을 콕 집어 "이 패턴을 따라줘"라고 적습니다.

용어 한 줄: 이렇게 이슈에 "우리 프로젝트가 이미 쓰는 방식(폼 라이브러리·검증 방식·인증 경로 등)을 그대로 따르라"고 콕 집어 알려주는 것을 따를 패턴(pattern to follow)이라고 불러요. 새 알바생에게 "우리 가게는 이렇게 해요" 하고 미리 일러주는 한마디와 같아요.

비유	클로드 코드에서	주의
새 알바생에게 "우리 가게 방식" 일러주기	이슈에 "따를 패턴" 적기	안 적으면 클로드 코드가 자기 방식으로 짬
이미 쓰는 레시피 카드 보여주기	참조 파일 한 개 콕 집어주기 (@경로)	글로 설명하기보다 실제 파일을 가리키는 게 정확함
가게 표준 컵·표준 시럽	이미 쓰는 폼·검증·인증 라이브러리	새 라이브러리를 새로 끌어오면 프로젝트가 잡탕이 됨

왜 이게 중요할까요? 같은 기능도 만드는 방식은 여러 가지입니다. 방식이 제각각이면 프로젝트 코드가 잡탕이 되고, 나중에 고치기도 힘듭니다. 그래서 "이미 우리가 쓰는 방식을 따르라"고 미리 못 박아두면, 결과가 프로젝트와 자연스럽게 어울립니다.

잘못된 예 (따를 패턴 없는 이슈):

## 설명
비밀번호 변경 기능을 만든다.

## 완료 조건
- 비밀번호 변경 폼 만들기
- 검증 추가

무슨 폼 라이브러리를 쓸지, 검증은 어떻게 할지 안 적혀 있습니다. 클로드 코드가 우리 프로젝트와 다른 라이브러리를 골라 새로 끌어올 수 있습니다.

올바른 예 (따를 패턴 명시한 이슈):

## 완료 조건
- 비밀번호 변경 폼 만들기
- 검증 추가

## 구현 참고사항
### 따를 패턴
- 참조: @app/actions/auth/login.ts (이미 있는 로그인 코드처럼 똑같은 모양으로)
- 폼은 이미 쓰는 폼 라이브러리 그대로 사용
- 검증은 이미 쓰는 검증 방식 그대로 사용

이미 있는 로그인 코드를 콕 집어 "이것처럼 만들어"라고 가리킵니다. 그러면 새 기능이 기존 코드와 같은 모양으로 나와 프로젝트와 잘 어울립니다.

이럴 때 이렇게: "따를 패턴"을 적을 때는 말로 길게 설명하기보다, 이미 있는 비슷한 파일 하나를 @경로로 콕 집어주는 게 가장 정확합니다. 클로드 코드가 그 파일을 직접 읽고 똑같은 모양으로 따라 짭니다.

짧게 정리

/decompose-issue는 큰 작업을 작은 이슈로 자동으로 쪼개줍니다. 5단계(분석 → 분해 → 의존성 → 출력 → 생성)로 움직입니다. 이슈 템플릿으로 제목/레이블/설명/완료 조건/의존성 형식을 통일합니다. 마지막에 "만들까요?"라고 물어본 뒤 사용자가 동의해야 깃허브에 올립니다.

---

14-5 이슈 작업하기

이렇게 막힌 적 있죠?

이슈를 잘 쪼개 놨습니다. 그런데 막상 하나를 해결하려니 또 막막합니다. 브랜치 만들고, 코드 보고, 고치고, 테스트하고, PR 올리고... 매번 이 긴 순서를 손으로 다 챙기다 보면 빼먹는 단계가 생깁니다.

이럴 때 이 긴 순서를 명령 한 줄로 자동 실행하면 어떨까요? 그게 /resolve-issue 명령입니다.

그게 바로 /resolve-issue

이슈 해결은 의사의 진료 과정과 닮았습니다. 1. 환자 정보 확인 → 이슈 불러오기 2. 진료실 준비 → 브랜치 세팅 3. 검사 → 코드베이스 분석 4. 진단 → 해결 계획 세우기 5. 치료 → 이슈 해결하기 6. 처방 기록 → 테스트 작성 7. 경과 확인 → 검증하기 8. 퇴원 서류 → 풀 리퀘스트 생성

이 8단계 진료 과정을 명령 한 줄로 자동화한 게 /resolve-issue입니다.

비유	클로드 코드에서	주의
의사의 진료 8단계	/resolve-issue 8단계	한 단계라도 빠지면 검증 안 된 코드가 나갈 수 있음
환자 번호로 차트 부르기	이슈 번호 하나로 시작	이슈가 잘 적혀 있어야 잘 해결됨
검사실에서 여러 검사 동시 진행	분석/검증을 서브에이전트로 병렬	동시에 시켜야 빨라짐

용어 한 줄: 브랜치(branch)란 원본을 건드리지 않고 따로 떼어내 작업하는 "사본 작업 공간"입니다. 원고를 복사해 거기에만 빨간펜을 대는 것과 같습니다. 용어 한 줄: 코드베이스란 그 프로젝트의 코드 전체를 묶어 부르는 말입니다. "이 책 전체"라고 할 때의 책 같은 것입니다. 용어 한 줄: 서브에이전트란 메인 클로드 코드가 일을 나눠 맡기는 보조 AI입니다. 사장이 직원에게 일을 나눠주는 것과 비슷합니다(7장).

/resolve-issue 8단계 자세히 보기

이 명령도 파일 하나로 만듭니다.

파일 위치: .claude/commands/resolve-issue.md

파일 핵심:

# 깃허브 이슈 해결하기
너는 지금부터 깃허브 이슈를 해결하는 뛰어난 개발자야.
아규먼트로 이슈 번호를 넘겨주면, 그 번호의 이슈를 해결해 줘.

8단계는 다음과 같습니다.

단계	하는 일	쉽게 말하면
1. 이슈 불러오기	gh CLI로 이슈 조회	제목/본문/레이블을 읽고 정확히 이해
2. 브랜치 세팅	issue-번호 브랜치 생성	예: issue-72 라는 작업 공간 만들기
3. 코드베이스 분석	서브에이전트로 조사	최대 10개 보조 AI가 코드를 동시에 살펴봄
4. 해결 계획 세우기	Scratchpad에 계획 적기	어떻게 풀지 생각을 글로 공개
5. 이슈 해결하기	서브에이전트로 구현	보조 AI 하나가 실제 코드 작성
6. 테스트 작성하기	유닛 테스트 작성	커버리지 80% 이상, 엣지 케이스 포함
7. 검증하기	테스트/린트/빌드 실행	각각 보조 AI가 동시에 검사
8. PR 생성	풀 리퀘스트 만들기	깃허브에 자동으로 PR 올림

용어 한 줄: Scratchpad란 클로드 코드가 생각과 계획을 적어두는 메모장입니다. 시험 볼 때 옆에 두고 끄적이는 연습장 같은 것입니다. 용어 한 줄: 유닛 테스트란 코드의 작은 부분 하나가 제대로 도는지 확인하는 자동 검사입니다. 부품 하나씩 따로 불량인지 점검하는 것과 같습니다. 용어 한 줄: 커버리지란 "코드 중 테스트가 점검한 비율"입니다. 80%면 코드의 80%가 검사를 거쳤다는 뜻입니다. 용어 한 줄: 엣지 케이스란 "잘 안 일어나지만 일어나면 골치 아픈 상황"입니다. 빈 칸 입력, 0으로 나누기 같은 경우입니다.

왜 "해결" 단계만 보조 AI 하나로 할까

분석과 검증은 여러 보조 AI에게 동시에 시키는데, 정작 해결(코드 작성)은 보조 AI 하나만 씁니다. 이상해 보이지만 이유가 있습니다.

잘못된 예 (해결도 여러 명에게 나눠 맡기면): 이미 이슈가 독립적으로 풀 수 있는 작은 단위로 나뉘어 있습니다. 그걸 또 쪼개는 건 어색합니다. 게다가 여러 보조 AI가 각자 짠 코드를 합칠 때 충돌이 납니다.

올바른 예 (해결은 한 명에게): 구현은 보조 AI 하나가 일관되게 담당합니다. 대신 코드 분석/테스트/검증은 병렬로 돌려 시간을 아낍니다. 이렇게 하면 작업 시간이 절반 이하로 줄고, 메인 AI의 기억 공간(컨텍스트)도 아낍니다.

용어 한 줄: 충돌(conflict)이란 두 사람이 같은 줄을 서로 다르게 고쳤을 때 "어느 걸 따를지" 부딪치는 상황입니다.

실제로 한 줄로 돌려보기

터미널 예:

# 186번 이슈를 해결할 때
> /resolve-issue 186

그러면 클로드 코드가 알아서:

1. 이슈 조회 (gh issue view ... --json title,body,labels,state)
2. issue-186 브랜치 생성
3. 보조 AI들이 코드베이스 분석
4. 해결 계획 수립
5. 코드 작성
6. 테스트 작성
7. 테스트/린트/빌드 검증
8. PR 자동 생성

복잡한 프롬프트를 길게 쓰지 않아도, 이슈 번호 하나로 해결부터 검증, PR까지 진행됩니다.

이럴 때 이렇게: 커맨드를 만들 때 가장 신경 쓸 부분은 "작업이 끝났는지 어떻게 확인할까?"입니다. 6단계 테스트와 7단계 검증을 빼먹으면, 끝난 줄 알았는데 망가진 코드가 PR로 나갈 수 있습니다. 그래서 테스트/검증 단계를 커맨드에 꼭 넣어둡니다.

짧게 정리

/resolve-issue는 이슈 번호 하나로 8단계를 자동 실행합니다. 분석과 검증은 서브에이전트로 병렬 처리해 빠릅니다. 해결(코드 작성)만은 보조 AI 하나가 맡아 충돌을 피합니다. 커맨드 설계의 핵심은 "완료를 어떻게 확인할지"입니다.

---

14-6 병렬로 이슈 작업하기

이렇게 막힌 적 있죠?

이슈를 5개 만들어 놨는데 하나씩 순서대로만 처리하면 너무 느립니다. 하나 끝날 때까지 나머지 4개는 가만히 기다립니다.

이럴 때 이슈 여러 개를 동시에 처리할 수 있다면 얼마나 빠를까요? 그걸 가능하게 하는 게 Git Worktree와 작은 셸 스크립트입니다.

그게 바로 병렬 이슈 작업

학교에 교실이 하나면 수학 끝나야 영어를 합니다(직렬). 교실이 여러 개면 수학, 영어, 과학을 동시에 합니다(병렬).

Git Worktree는 교실(작업 공간)을 추가로 만드는 기능입니다. 각 교실에서 별도의 클로드 코드가 동시에 다른 이슈를 풉니다.

비유	클로드 코드에서	주의
교실 1개 → 순서대로	직렬 작업 (이슈 하나씩)	안전하지만 느림
교실 여러 개 → 동시	병렬 작업 (Git Worktree)	빠르지만 충돌 위험. 독립 이슈끼리만
새 교실 만들기	git worktree add	교실(작업 공간)이 따로라 서로 안 섞임

용어 한 줄: Git Worktree란 한 저장소에서 여러 브랜치를 각각 다른 폴더로 동시에 펼쳐놓는 기능입니다. 같은 원고를 여러 책상에 동시에 펼쳐놓고 각자 다른 장을 손보는 것과 같습니다(13장). 용어 한 줄: 셸 스크립트란 터미널 명령 여러 줄을 한 파일에 적어 한 번에 실행하는 "자동 실행 메모"입니다. 아침 루틴을 순서대로 적어 한 번에 처리하는 체크리스트 같은 것입니다.

create-worktree.sh — 작업 공간 자동 생성 스크립트

워크트리를 만들고, 그 안으로 들어가, 곧바로 이슈 해결까지 시키는 일을 스크립트 하나로 묶을 수 있습니다. 처음엔 이 스크립트를 외울 필요 없습니다. 무슨 일을 하는지만 보면 됩니다.

#!/bin/bash
if [ $# -eq 0 ]; then
    echo "Error: Worktree 이름을 명시해주세요!"
    return 1
fi
ARGUMENT=$1
WORKTREE_PATH="../폴더이름/$ARGUMENT"

# 워크트리 생성 → 그 폴더로 이동 → 클로드 실행
if git worktree add "$WORKTREE_PATH"; then
    echo "Worktree 생성 성공: $WORKTREE_PATH"
    cd "$WORKTREE_PATH" || exit 1

    # 이름 끝에서 이슈 번호 뽑아 자동으로 /resolve-issue 실행
    ISSUE_NUMBER=$(echo "$ARGUMENT" | awk -F'-' '{print $NF}')
    if [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
        echo "이슈 해결 시작: $ISSUE_NUMBER"
        claude -p "/user:resolve-issue $ISSUE_NUMBER"
    else
        echo "Warning: 이슈 번호를 못 찾음."
    fi
else
    echo "Worktree 생성 실패."
    exit 1
fi

이 스크립트가 하는 일을 한 문장씩 풀면: 새 작업 공간(워크트리)을 만들고, 그 안으로 이동한 뒤, 이름 끝의 숫자(이슈 번호)를 뽑아, 그 번호로 /resolve-issue를 자동으로 돌립니다.

용어 한 줄: claude -p 란 사람이 일일이 답하지 않아도 클로드 코드가 알아서 끝까지 실행하는 "자동 모드"입니다. 이를 헤드리스 모드라고 부릅니다. 밥솥에 예약 버튼 눌러두고 자는 것과 같습니다.

병렬 작업 전체 흐름 따라 하기

순서대로 따라 하면 됩니다.

단계 1: 터미널 여러 개 열기

단계 2: 각 터미널에서 워크트리 생성
  터미널 1: ./create-worktree.sh issue-79
  터미널 2: ./create-worktree.sh issue-80
  터미널 3: ./create-worktree.sh issue-81

단계 3: 각 워크트리에서 자동으로 이슈 해결
  (스크립트가 /resolve-issue 를 알아서 실행)

단계 4: 끝난 PR들을 메인 브랜치로 병합
  git checkout main
  git merge issue-79
  git merge issue-80
  git merge issue-81

용어 한 줄: 병합(merge)이란 따로 작업한 사본의 변경을 원본에 합치는 일입니다. 여러 사람이 나눠 쓴 보고서를 하나로 합치는 것과 같습니다.

매니저처럼 일하는 4단계

병렬 작업을 할 때 나는 코딩하는 사람이라기보다 작업을 나눠주는 매니저에 가깝습니다. 운영은 다음 4단계로 돌아갑니다.

1. 만들고 있는 서비스를 보며 필요한 요구사항을 정리한다.
2. 요구사항을 작은 이슈로 쪼개도록 클로드 코드에게 시키고 깃허브에 올린다.
3. 필요한 만큼 워크트리를 병렬로 만들어 클로드 코드가 PR을 올리게 한다.
4. 깃허브에서 변경 사항을 살펴본 뒤 메인 브랜치로 병합한다.

잘 안 될 때 고치는 법 (주니어 다루듯)

병렬 작업이 매끄럽지 않을 때, 신입 개발자에게 코칭하듯 조정하면 됩니다.

문제	이렇게 해결
이슈가 너무 큰 단위로 나뉘었다	더 작은 이슈로 다시 쪼갠다
충돌이 너무 자주 난다	서로 독립적인 이슈로 나눠 의존성을 줄인다
테스트가 충분히 안 써진다	커맨드에 테스트 요구사항을 더 강하게 적는다
AI가 프로젝트를 잘 못 다룬다	작업 흐름을 점검하고, 맡기는 양을 줄이고, 설명을 더 붙인다

잘못된 예 vs 올바른 예: 잘못된 예 — 서로 의존하는 두 이슈(예: #1이 끝나야 #2 가능)를 동시에 병렬로 돌리면 충돌과 꼬임이 납니다. 올바른 예 — 독립적인 이슈끼리만 병렬로 묶고, 의존 관계가 있는 이슈는 순서대로 처리합니다.

짧게 정리

Git Worktree로 여러 작업 공간을 만들어 이슈를 동시에 처리합니다. create-worktree.sh가 워크트리 생성 → 클로드 실행 → 이슈 해결을 자동화합니다. claude -p(헤드리스 모드)로 사람이 안 지켜봐도 끝까지 돕니다. 잘 안 되면 이슈를 더 잘게 쪼개고 프롬프트를 다듬어 해결합니다.

---

연습문제

Q1. 깃허브 이슈의 구성 요소를 모두 나열하고, 각각의 역할을 한 줄로 설명하세요.

A. (1) 제목과 본문 — 무슨 일인지 전달, (2) 담당자 — 누가 할지 지정, (3) 레이블 — 종류/우선순위를 색으로 구분, (4) 마일스톤 — 목표/버전끼리 묶음, (5) 프로젝트 — 칸반 보드로 시각 관리, (6) 연결된 풀 리퀘스트 — 고친 코드를 이슈에 연결.

Q2. /resolve-issue 명령의 8단계를 순서대로 나열하세요.

A. (1) 이슈 불러오기, (2) 브랜치 세팅, (3) 코드베이스 분석, (4) 해결 계획 세우기, (5) 이슈 해결하기, (6) 테스트 작성, (7) 검증하기(테스트/린트/빌드), (8) 풀 리퀘스트 생성. 핵심은 "완료를 어떻게 확인하고 점검할지"를 설계하는 것입니다.

Q3. 복잡도 레이블(복잡/보통/쉬움)이 클로드 모델 선택과 어떻게 연결되는지 설명하세요.

A. 어려운 이슈(복잡도:복잡)에는 성능이 높은 클로드 Opus를, 쉬운 이슈(복잡도:쉬움)에는 빠르고 비용 효율적인 클로드 Sonnet을 씁니다. 레이블로 난이도를 표시해두면 작업을 나눠 맡길 때 적절한 모델을 고르는 기준이 됩니다. (어떤 난이도에 어떤 모델이 맞는지는 바뀔 수 있으니 최신 값은 공식 문서에서 확인하세요.)

Q4. Git Worktree를 활용한 병렬 이슈 작업의 장점과 주의점은 무엇인가요?

A. 장점 — 여러 이슈를 독립된 작업 공간에서 동시에 해결해 속도가 크게 빨라집니다. 주의점 — 이슈가 너무 크거나 서로 의존적이면 충돌이 납니다. 그래서 독립적인 작은 이슈 단위로 쪼개고, 병합 전에 코드와 프로젝트가 잘 맞는지 반드시 확인해야 합니다.

---

핵심 정리 한눈에 보기

항목	/decompose-issue	/resolve-issue
목적	큰 작업을 작은 이슈로 쪼개기	이슈 하나를 끝까지 해결
입력	작업 설명 (글)	이슈 번호 (숫자)
출력	이슈 목록 → 깃허브에 생성	코드 + 테스트 + PR
단계	5단계 (분석→분해→의존성→출력→생성)	8단계 (불러오기→브랜치→분석→계획→해결→테스트→검증→PR)
서브에이전트	안 씀	분석/테스트/검증에 병렬 사용

항목	직렬 작업	병렬 작업 (Worktree)
동시 처리 수	1개	여러 개
속도	느림	빠름
충돌 위험	낮음	있음 (독립 이슈로 최소화)
필요한 것	터미널 1개	터미널 여러 개 + create-worktree.sh
잘 맞는 상황	의존성 있는 이슈	독립적인 이슈들

---

더 학습할 자료

자료	설명
https://cli.github.com	gh CLI 공식 사이트 및 설치 가이드
https://docs.github.com	깃허브 공식 문서 (이슈, PR, Projects 등)
https://github.com/codefactory-co	이 책 저자의 깃허브 (예제 코드)
5장 커스텀 슬래시 커맨드	/명령 만드는 법 (앞 장)
7장 서브에이전트	보조 AI 활용법 (앞 장)
13장 Git Worktree	워크트리 기본 개념 (앞 장)

이 장의 요금/모델명/MCP/버전 같은 정보는 빠르게 바뀝니다. 구체 값은 항상 클로드 코드 공식 문서에서 다시 확인하세요.

---

다음 장 예고: 다음 장에서는 또 다른 주제로 클로드 코드 활용을 이어갑니다. 지금 그 내용을 몰라도 이 장을 이해하는 데는 전혀 문제가 없습니다.